Stasis is fairly simple. It plays samples at a certain speed calculated from the various pitch settings.
File Format
===========
The type 1 file format is as follows:
[4 bytes] The string "Sta1"
[20 bytes] The sample name
[word] The sample length
[word] The repeat offset
[word] The repeat length
[word] The finetune value
[word] The offset from the start of the file to the start of the data. Usually 44.
Sample data follows...
The data is logarithmic in the normal VIDC format, so has the sign in bit 0.
Repeats
=======
To provide a sustained sound, Stasis can repeat a section of the sample continuously. A repeat is specified as an offset in bytes from the start of the sample data, and a length. If the repeat length is >2, the module will jump back to the repeat offset when the sound reaches the position [repeat offset+repeat length].
SWIs
====
The SWIs roughly follow the structure of the command they mimic. For example, for the command *StasisLoad <slot> <filename> there is an SWI "Stasis_Load" where R0 contains the slot and R1 points to a filename string. The exception is *StasisSave, where R2 specifies which format (0=stasis, 1=tracker) and R0, R1 the slot, filename.
Here is a full list of SWIs:
Stasis_Sample - set repeat length to zero for no repeat
Stasis_Load
Stasis_Save
Stasis_Link
Stasis_Name
Stasis_FineTune
Stasis_VolSlide - see below
Stasis_PitchSlide - see below
Stasis_Volume - R0,R1 are channel,volume (0-&7F)
Stasis_GetAddress - returns the address of the Stasis internal variables. To retain compatibility you should not write directly to this block (and thatæs why Iæm not going to tell you whatæs in it).
Stasis_Control - control various Stasis features. Stasis_Control takes a value in R0, and a bit mask in R1. The bits do this:
Bit 0 - turns on overdrive
Bit 1 - stop sounds being issued
Bit 2 - start samples from their repeat offsets
Bit 3 - activate pitch and volume sliding
Bit 4 - report errors
Bit 4 is normally set when Stasis is loaded, but can be unset by loading the module with the command *RMLoad <filepath>Stasis game. This stops recoverable error (like attempts to play empty slots) being reported, and reconfigures the sound system to suit Stasis on entry (the buffer length and sample period).
Stasis_Load may in future use R2 to specify which area to load the sample into. Please set R2=0 if you use this SWI.
Note that *StasisTune has no corresponding SWI. An even briefer summary can be obtained with *Help StasisSWIs.
A few SWI details
=================
Command *StasisSample
SWI "Stasis_Sample"
R0 - slot (0-63)
R1 - start address
R2 - length
R3 - repeat offset
R4 - repeat length
Returns - previous values in R0-R4.
Stasis_Sample has a few more uses. If any value R1 to R4 is -1, the current value is returned. If the sample address is 0, the sample in the slot (if any) is deallocated and its memory freed. If the repeat length is 0 (or 1,2), the repeat is disabled.
In similar fashion, if Stasis_Finetune is called with R1=-1, the current value is returned. Stasis_Control returns the current control value in R0, so to read call with R0=R1=0
Speed
=====
Stasis uses a fast fill loop (5*&D0 instructions + 8 branches) by first checking that it wonæt need to jump to repeat or finish the sample. Just about any sample can be played correctly, but very short, looped samples will take more processor time. The fast loop can only be used if the sound buffer has its default length (&D0). The module will complain if the length is different. In particular, using some Tracker players at the same time as Stasis may downgrade the optimisation of the module, if it works at all.
Volume and Pitch Slides
=======================
Stasis currently supports basic volume and pitch sliding (ie the volume/pitch can be made to increase/decrease over time). The system isnæt intended for general use in this release, so itæs tricky to use. If you want to, first issue the SWI "Stasis_Control" once, with R0=R1=8. Then issue the SWI "Stasis_VolSlide" or "Stasis_PitchSide" as necessary. The parameters passed should be:
R0 The channel number 1-8
R1 The value to be added to the pitch/voloume on each buffer fill (about 100 times/sec).
R2 The 'target value' - when reached, the slide stops. R1 contains a normal pitch value or a volume in the scale 0-&FFFF (&FFFF = max).
To make things more awkward, the SWI needs to be called with R1=0 to cancel the slide before the next sound. Otherwise the slide will be applied to all subsequent sounds on that channel.
The volume and pitch slide mechanism is due to be rewritten. In particular, slides will be specified as a target value and a time in which that target value should be reached. Therefore any program which uses pitch slides may not be compatible with future releases.
Other Guidelines
================
Stasis will be modified in the future to provide the following:
Å Proper handling of duration values.
Å Easy to use volume & pitch slides.
With this in mind, always set duration values to zero and donæt use volume and pitch slides. Otherwise load this version of the module in your !Run file ie donæt do the RMEnsure business.
